fix(chat): never leave a client tool call unanswered on the server - #807

Summary

Fixes five defects found reviewing the shipped client-tool continuation stack (#782–#805). Four violate one invariant the architecture depended on but never stated:

The server thread must never hold a client tool call without a corresponding tool result.

When violated, the thread holds an AIMessage(tool_calls=[…]) with no ToolMessage, and most providers reject that history with a 400 on the next user turn.

The central change

ClientToolsCapability gains flush(), making the three settlement verbs distinct:

AG-UI's flush() is a no-op — its settle() already calls addMessage. LangGraph's batches the buffer into one threads.updateState write (no asNode, so add_messages appends and the resume point is untouched), falling back to draining into the next submit() when the transport has no updateState.

The five defects

1. followUp: false corrupted LangGraph threads. When every tool in a group was terminal, resolve() was never called — and it was the only thing that drained the buffer. Results never reached the server. AG-UI was immune, which is what made the asymmetry easy to miss.
2. Aborted tools re-executed. The abort path returned without settling, so the call stayed in pending() and was re-dispatched after the next run — a second execution of a side-effecting handler the user explicitly stopped.
3. The max-turns guard discarded results. An ask tool's user-supplied answer was thrown away and the calls left unsettled. Now real results are preserved and only never-executed tools get a limit error.
4. agent.stop wrappers stacked without bound. Now wrapped once per agent via a registry and restored on destroy.
5. Postgres tenant_id was written but never filtered on. Now NOT NULL DEFAULT '', in the primary key and every WHERE/conflict target.

Behavior changes worth calling out

• Abort now writes to the server (a cancelled tool result) where it was previously a silent no-op.
• The max-turns guard now writes to the server where it previously dropped results.

Both are required to hold the invariant, but both are observable.

Schema change

threadplane_client_tool_executions gains tenant_id in its primary key. No migration tooling — the table is recreated. Authorized explicitly; no backward compatibility required.

Verification

Live, against a real LLM and a real LangGraph backend — the decisive test, because the failure is a provider rejection of persisted server state that no unit test can reproduce:

1. Model called the terminal show_trip_summary tool → no follow-up run fired, and GET /threads/{id}/state showed the ToolMessage present. Unanswered tool calls: none.
2. Reloaded, sent another message → normal reply, no 400. This is the scenario that was broken.
3. Zero console errors; zero tool-call errors in the backend log.

Automated: 1102 passing in chat, 294 in langgraph, 206 in ag-ui, 46 in middleware, 103 in examples-chat-angular. Lint errors: 0 across all five. API docs regenerated for the new public surface (flush, settleWithoutContinuing, cancelledClientToolResult).

Review notes

Each batch was adversarially reviewed, and the reviews caught four defects that the plan and the implementations both missed — worth knowing since three came from following the plan literally:

• flush() originally left its batch in the buffer across the await, but two other mutators clear that buffer unconditionally — it could destroy an unpersisted result and double-send a persisted one.
• The plan put the flush inside the per-call blocked branch, so an N-call group fired N flushes and LangGraph's in-flight short-circuit stranded all but the first.
• Settling on abort via the default channel (cap.resolve) meant Stop submitted a run. Fixed with a settle-only channel that can never fall back to resolve.
• Re-staging a failed flush after a thread switch would inject the old thread's messages into the new one. Fixed with a buffer generation guard.

Known follow-up (not fixed here)

When a custom transport lacks updateState, persistFn is undefined and flush() resolves with no diagnostic — the coordinator can't distinguish that from a real write. The submit-drain fallback still covers it, so the residual exposure is a reload before the user's next message. Closing it properly needs a signal on the capability contract.

Spec: docs/superpowers/specs/2026-08-07-client-tool-continuation-fixes-design.md
Plan: docs/superpowers/plans/2026-08-07-client-tool-continuation-fixes.md

🤖 Generated with Claude Code